1 PHP SmartyPants 2 =============== 3 4 Version 1.5.1e - Fri 9 Dec 2005 5 6 by Michel Fortin 7 <http://www.michelf.com/> 8 9 based on work by John Gruber 10 <http://daringfireball.net/> 11 12 13 Introduction 14 ------------ 15 16 PHP SmartyPants is a port to PHP of the original SmartyPants written 17 in Perl by John Gruber. 18 19 PHP SmartyPants is a free web publishing plug-in for WordPress and 20 Smarty template engine that easily translates plain ASCII punctuation 21 characters into "smart" typographic punctuation HTML entities. 22 SmartyPants can also be invoked as a standalone PHP function. 23 24 SmartyPants can perform the following transformations: 25 26 * Straight quotes (`"` and `'`) into "curly" quote HTML entities 27 * Backtick-style quotes (` ``like this'' `) into "curly" quote HTML 28 entities 29 * Dashes (`--` and `---`) into en- and em-dash entities 30 * Three consecutive dots (`...`) into an ellipsis entity 31 32 This means you can write, edit, and save using plain old ASCII straight 33 quotes, plain dashes, and plain dots, but your published posts (and 34 final HTML output) will appear with smart quotes, em-dashes, and proper 35 ellipses. 36 37 SmartyPants does not modify characters within `<pre>`, `<code>`, 38 `<kbd>`, or `<script>` tag blocks. Typically, these tags are used to 39 display text where smart quotes and other "smart punctuation" would not 40 be appropriate, such as source code or example markup. 41 42 43 ### Backslash Escapes ### 44 45 If you need to use literal straight quotes (or plain hyphens and 46 periods), SmartyPants accepts the following backslash escape sequences 47 to force non-smart punctuation. It does so by transforming the escape 48 sequence into a decimal-encoded HTML entity: 49 50 51 Escape Value Character 52 ------ ----- --------- 53 \\ \ \ 54 \" " " 55 \' ' ' 56 \. . . 57 \- - - 58 \` ` ` 59 60 61 This is useful, for example, when you want to use straight quotes as 62 foot and inch marks: 63 64 6\'2\" tall 65 66 translates into: 67 68 6'2" tall 69 70 in SmartyPants's HTML output. Which, when rendered by a web browser, 71 looks like: 72 73 6'2" tall 74 75 76 Installation and Requirement 77 ---------------------------- 78 79 PHP SmartyPants require PHP version 4.0.5 or later. 80 81 82 ### WordPress ### 83 84 WordPress already include a filter called "Texturize" with the same 85 goal as SmartyPants. You could still find some usefulness to 86 PHP SmartyPants if you are not happy enough with the standard algorithm. 87 88 PHP SmartyPants works with [WordPress][wp], version 1.2 or later. 89 90 [wp]: http://wordpress.org/ 91 92 1. To use PHP SmartyPants with WordPress, place the "smartypants.php" 93 file in the "plugins" folder. This folder is hidden inside 94 "wp-content" at the root of your site: 95 96 (site home)/wp-content/plugins/smartypants.php 97 98 2. Activate the plugin with the administrative interface of WordPress. 99 In the "Plugins" section you will now find SmartyPants. To activate 100 the plugin, click on the "Activate" button on the same line than 101 SmartyPants. Your entries will now be filtered by PHP SmartyPants. 102 103 Note: It is not possible at this time to apply a different set of 104 filters to different entries. All your entries will be filtered by 105 PHP SmartyPants if the plugin is active. This is currently a limitation 106 of WordPress. 107 108 109 ### Blosxom ### 110 111 SmartyPants works with Blosxom version 2.0 or later. 112 113 1. Rename the "SmartyPants.pl" plug-in to "SmartyPants" (case is 114 important). Movable Type requires plug-ins to have a ".pl" 115 extension; Blosxom forbids it (at least as of this writing). 116 117 2. Copy the "SmartyPants" plug-in file to your Blosxom plug-ins folder. 118 If you're not sure where your Blosxom plug-ins folder is, see the 119 Blosxom documentation for information. 120 121 3. That's it. The entries in your weblog should now automatically have 122 SmartyPants's default transformations applied. 123 124 4. If you wish to configure SmartyPants's behavior, open the 125 "SmartyPants" plug-in, and edit the value of the `$smartypants_attr` 126 configuration variable, located near the top of the script. The 127 default value is 1; see "Options", below, for the full list of 128 supported values. 129 130 131 ### In your programs ### 132 133 You can use PHP SmartyPants easily in your current PHP program. Simply 134 include the file and then call the `SmartyPants` function on the text 135 you want to convert: 136 137 include_once "smartypants.php"; 138 $my_text = SmartyPants($my_text); 139 140 141 ### With Smarty ### 142 143 If your program use the [Smarty][sm] template engine, PHP SmartyPants 144 can now be used as a modifier for your templates. Rename 145 "smartypants.php" to "modifier.smartypants.php" and put it in your 146 smarty plugins folder. 147 148 [sm]: http://smarty.php.net/ 149 150 151 Options and Configuration 152 ------------------------- 153 154 Settings are specified by editing the value of the `$smartypants_attr` 155 variable in the "smartypants.php" file. For users of the Smarty template 156 engine, the "smartypants" modifier also takes an optional attribute where 157 you can specify configuration options, like this: 158 `{$var|smartypants:1}` (where "1" is the configuration option). 159 160 Numeric values are the easiest way to configure SmartyPants's behavior: 161 162 "0" 163 Suppress all transformations. (Do nothing.) 164 165 "1" 166 Performs default SmartyPants transformations: quotes (including 167 backticks-style), em-dashes, and ellipses. `--` (dash dash) is 168 used to signify an em-dash; there is no support for en-dashes. 169 170 "2" 171 Same as smarty_pants="1", except that it uses the old-school 172 typewriter shorthand for dashes: `--` (dash dash) for en-dashes, 173 `---` (dash dash dash) for em-dashes. 174 175 "3" 176 Same as smarty_pants="2", but inverts the shorthand for dashes: `--` 177 (dash dash) for em-dashes, and `---` (dash dash dash) for en-dashes. 178 179 "-1" 180 Stupefy mode. Reverses the SmartyPants transformation process, 181 turning the HTML entities produced by SmartyPants into their ASCII 182 equivalents. E.g. `“` is turned into a simple double-quote 183 (`"`), `—` is turned into two dashes, etc. This is useful if you 184 wish to suppress smart punctuation in specific pages, such as 185 RSS feeds. 186 187 The following single-character attribute values can be combined to 188 toggle individual transformations from within the smarty_pants 189 attribute. For example, to educate normal quotes and em-dashes, but not 190 ellipses or backticks-style quotes: 191 192 $smartypants_attr = "qd"; 193 194 Or inside a Smarty template: 195 196 {$var|smartypants:"qd"} 197 198 "q" 199 Educates normal quote characters: (`"`) and (`'`). 200 201 "b" 202 Educates ` ``backticks'' ` double quotes. 203 204 "B" 205 Educates backticks-style double quotes and ` `single' ` quotes. 206 207 "d" 208 Educates em-dashes. 209 210 "D" 211 Educates em-dashes and en-dashes, using old-school typewriter 212 shorthand: (dash dash) for en-dashes, (dash dash dash) for 213 em-dashes. 214 215 "i" 216 Educates em-dashes and en-dashes, using inverted old-school 217 typewriter shorthand: (dash dash) for em-dashes, (dash dash dash) 218 for en-dashes. 219 220 "e" 221 Educates ellipses. 222 223 "w" 224 Translates any instance of `"` into a normal double-quote 225 character. This should be of no interest to most people, but of 226 particular interest to anyone who writes their posts using 227 Dreamweaver, as Dreamweaver inexplicably uses this entity to 228 represent a literal double-quote character. SmartyPants only 229 educates normal quotes, not entities (because ordinarily, entities 230 are used for the explicit purpose of representing the specific 231 character they represent). The "w" option must be used in 232 conjunction with one (or both) of the other quote options ("q" or 233 "b"). Thus, if you wish to apply all SmartyPants transformations 234 (quotes, en- and em-dashes, and ellipses) and also translate 235 `"` entities into regular quotes so SmartyPants can educate 236 them, you should pass the following to the smarty_pants attribute: 237 238 $smartypants_attr = "qDew"; 239 240 Inside a Smarty template, this will be: 241 242 {$var|smartypants:"qDew"} 243 244 245 Caveats 246 ------- 247 248 ### Why You Might Not Want to Use Smart Quotes in Your Weblog ### 249 250 For one thing, you might not care. 251 252 Most normal, mentally stable individuals do not take notice of proper 253 typographic punctuation. Many design and typography nerds, however, 254 break out in a nasty rash when they encounter, say, a restaurant sign 255 that uses a straight apostrophe to spell "Joe's". 256 257 If you're the sort of person who just doesn't care, you might well want 258 to continue not caring. Using straight quotes -- and sticking to the 259 7-bit ASCII character set in general -- is certainly a simpler way to 260 live. 261 262 Even if you *do* care about accurate typography, you still might want to 263 think twice before educating the quote characters in your weblog. One 264 side effect of publishing curly quote HTML entities is that it makes 265 your weblog a bit harder for others to quote from using copy-and-paste. 266 What happens is that when someone copies text from your blog, the copied 267 text contains the 8-bit curly quote characters (as well as the 8-bit 268 characters for em-dashes and ellipses, if you use these options). These 269 characters are not standard across different text encoding methods, 270 which is why they need to be encoded as HTML entities. 271 272 People copying text from your weblog, however, may not notice that 273 you're using curly quotes, and they'll go ahead and paste the unencoded 274 8-bit characters copied from their browser into an email message or 275 their own weblog. When pasted as raw "smart quotes", these characters 276 are likely to get mangled beyond recognition. 277 278 That said, my own opinion is that any decent text editor or email client 279 makes it easy to stupefy smart quote characters into their 7-bit 280 equivalents, and I don't consider it my problem if you're using an 281 indecent text editor or email client. 282 283 ### Algorithmic Shortcomings ### 284 285 One situation in which quotes will get curled the wrong way is when 286 apostrophes are used at the start of leading contractions. For example: 287 288 'Twas the night before Christmas. 289 290 In the case above, SmartyPants will turn the apostrophe into an opening 291 single-quote, when in fact it should be a closing one. I don't think 292 this problem can be solved in the general case -- every word processor 293 I've tried gets this wrong as well. In such cases, it's best to use the 294 proper HTML entity for closing single-quotes (`’` or `’`) by 295 hand. 296 297 298 Bugs 299 ---- 300 301 To file bug reports or feature requests (other than topics listed in the 302 Caveats section above) please send email to: 303 304 <michel.fortin (a] michelf.com> 305 306 If the bug involves quotes being curled the wrong way, please send 307 example text to illustrate. 308 309 310 Version History 311 --------------- 312 313 1.5.1e (9 Dec 2005) 314 315 * Corrected a bug that prevented special characters from being 316 escaped. 317 318 319 1.5.1d (6 Jun 2005) 320 321 * Correct a small bug in `_TokenizeHTML` where a Doctype declaration 322 was not seen as HTML, making curly quotes inside it. 323 324 325 1.5.1c (13 Dec 2004) 326 327 * Changed a regular expression in `_TokenizeHTML` that could lead 328 to a segmentation fault with PHP 4.3.8 on Linux. 329 330 331 1.5.1b (6 Sep 2004) 332 333 * Corrected a problem with quotes immediately following a dash 334 with no space between: `Text--"quoted text"--text.` 335 336 * PHP SmartyPants can now be used as a modifier by the Smarty 337 template engine. Rename the file to "modifier.smartypants.php" 338 and put it in your smarty plugins folder. 339 340 * Replaced a lot of spaces characters by tabs, saving about 4 KB. 341 342 343 1.5.1a (30 Jun 2004) 344 345 * PHP Markdown and PHP Smartypants now share the same `_TokenizeHTML` 346 function when loaded simultanously. 347 348 * Changed the internals of `_TokenizeHTML` to lower the PHP version 349 requirement to PHP 4.0.5. 350 351 352 1.5.1 (6 Jun 2004) 353 354 * Initial release of PHP SmartyPants, based on version 1.5.1 of the 355 original SmartyPants written in Perl. 356 357 358 Copyright and License 359 --------------------- 360 361 Copyright (c) 2005 Michel Fortin 362 <http://www.michelf.com/> 363 All rights reserved. 364 365 Copyright (c) 2003-2004 John Gruber 366 <http://daringfireball.net/> 367 All rights reserved. 368 369 Redistribution and use in source and binary forms, with or without 370 modification, are permitted provided that the following conditions are 371 met: 372 373 * Redistributions of source code must retain the above copyright notice, 374 this list of conditions and the following disclaimer. 375 376 * Redistributions in binary form must reproduce the above copyright 377 notice, this list of conditions and the following disclaimer in the 378 documentation and/or other materials provided with the distribution. 379 380 * Neither the name "SmartyPants" nor the names of its contributors may 381 be used to endorse or promote products derived from this software 382 without specific prior written permission. 383 384 This software is provided by the copyright holders and contributors "as 385 is" and any express or implied warranties, including, but not limited 386 to, the implied warranties of merchantability and fitness for a 387 particular purpose are disclaimed. In no event shall the copyright owner 388 or contributors be liable for any direct, indirect, incidental, special, 389 exemplary, or consequential damages (including, but not limited to, 390 procurement of substitute goods or services; loss of use, data, or 391 profits; or business interruption) however caused and on any theory of 392 liability, whether in contract, strict liability, or tort (including 393 negligence or otherwise) arising in any way out of the use of this 394 software, even if advised of the possibility of such damage. 395
